CSM34 STEP 1 -- generischer GOP-Test mit 1024x768
================================================
Datum: 03.10.2026

Die Datei csm34.efi in DIESEM Paket ist ein Test VOR dem XP-Start.
Sie ist noch kein vga.sys und startet XP nicht. Der vorhandene BSE4-Treiber
setzt im gelieferten Quellcode weiterhin 1920x1080 voraus. Ihn bereits mit
einem auf 1024x768 umgestellten Framebuffer zu starten waere kein gueltiger
Test des neuen Grafikpfads.

ERSTER TEST AUF DEM GIGABYTE
---------------------------
1. csm34.efi neben die bisher verwendete EFI-Datei kopieren.
   Die bisher funktionierende Startdatei fuer XP behalten.
2. csm34.efi ueber die UEFI-Shell oder die vorhandene Funktion zum Starten
   einer bestimmten EFI-Datei aufrufen.
3. Das vollstaendige Pruefbild fotografieren.
4. ESC versucht den vorherigen Grafikmodus wiederherzustellen und kehrt
   zur UEFI-Umgebung zurueck. R startet den Rechner neu.

Die gleiche csm34.efi ist fuer die Intel-iGPU und die NVIDIA GT 730 gedacht,
jeweils einzeln auf dem Gigabyte. Der Monitor muss am jeweils verwendeten
Ausgang angeschlossen sein; UEFI muss diese Ausgabe als primaer benutzen.
Es gibt keine getrennte Intel-/NVIDIA-Datei und keine fest angenommene
PCI-Adresse, Framebuffer-Adresse oder GOP-Modusnummer.

Falls die Firmware mehrere unabhaengige aktive Framebuffer meldet und die
primaere Konsole nicht eindeutig zugeordnet werden kann, erfolgt keine
Modusumschaltung. Die Diagnose zeigt dann Selection error=5. Das ist eine
bewusste Grenze: kein stiller Wechsel auf die andere Grafikkarte.

WAS AUF DEM BILDSCHIRM STEHEN SOLL
---------------------------------
RESULT: SET 1024X768 OK
oder
RESULT: ALREADY 1024X768

NOW: 1024X768
Ein weisser Rahmen muss an allen vier Raendern zu sehen sein.
Unten stehen fuenf Farbfaechen: RED, GREEN, BLUE, WHITE, BLACK.
Die Farben muessen zu den Beschriftungen passen.

PITCH darf groesser als 1024 sein. Er stammt vom GOP; es wird nicht
unterstellt, dass eine Zeile immer genau 4096 Byte belegt.
FB und SIZE werden vollstaendig mit 64 Bit angezeigt und uebergeben.
Bei Standard-RGB/BGR werden die definierten Farbmasken verwendet;
undefinierte PixelInformation-Felder dieser Standardformate werden ignoriert.

Falls 1024x768 nicht angeboten wird, bleibt der vorhandene gueltige Modus
aktiv. RESULT erklaert dies. Nach einem fehlerhaften SetMode wird versucht,
den vorherigen Modus wiederherzustellen. Ein Firmware-Haenger innerhalb
SetMode kann von einem normalen EFI-Aufrufer nicht abgefangen werden.

WAS DIESE VERSION PRUEFT
-----------------------
- Generische Auswahl einer bereits gueltigen GOP-Ausgabe.
- Suche nach 1024x768 in den vom GOP angebotenen Modi.
- Erneutes Lesen von Framebuffer, Groesse, Geometrie, Pitch und Pixelformat
  nach einem Moduswechsel; keine Wiederverwendung der alten Adresse.
- Direkte CPU-Schreibzugriffe auf diesen Framebuffer, ohne GOP.Blt und ohne
  UEFI-Textausgabe nach dem erfolgreichen Wechsel.
- Vorbereiten des bestehenden 72-Byte-Datensatzes GOP23V1. Seine ABI und
  die 64-Bit-Adressfelder bleiben erhalten.

Die Anzeige HANDOFF READY besagt, dass der Datensatz im Test vorbereitet ist.
Er wird in diesem Schritt noch nicht von XP verwendet. Ein erfolgreiches
Pruefbild belegt noch keinen XP-Boot und keine korrekte PAE-Abbildung im
spaeteren 32-Bit-Treiber.

Der Test schreibt keine Datentraegerdateien, aendert keine Boot-Eintraege
und programmiert keine PCI-BARs um. COM1 wird nicht initialisiert oder als
privater Diagnosekanal verwendet. Die UEFI-Watchdog-Zeitbegrenzung wird fuer
das Fotografieren des Pruefbildes abgeschaltet.

GRENZEN DIESES ERSTEN SCHRITTS
----------------------------
- 32-Bit-Pixel: RGBX, BGRX oder passende nicht ueberlappende 32-Bit-Masken.
- PixelBltOnly, 16-/24-Bit-Modi oder nicht initialisierte GOP-Ausgaben
  werden nicht als 32-Bit-Framebuffer ausgegeben.
- Keine Wiederinitialisierung einer ausgeschalteten GPU und kein Standby.
- Maximal 32 GOP-Handles und 4096 gemeldete Modi; bei Ueberschreitung wird
  nicht stillschweigend eine abgeschnittene Liste als vollstaendig behandelt.

BUILD UND PRUEFUNGEN
-------------------
Linux: Python 3.8+, GNU binutils, Zig 0.13.0; fuer Hostpruefungen GCC/Clang.

    python3 -m pip install ziglang==0.13.0
    python3 source/build_full.py
    python3 source/verify_gop.py

Alternativ den Pfad zum Zig-Compiler ueber CSM34_ZIG angeben.
source/build.py ist ein kurzer Aufruf desselben Builds.
Die Ausgabe csm34.efi ist standardmaessig ausschliesslich der STEP1-Test.

    python3 source/build_full.py --integration-check

Dieser Zusatz kompiliert auch den zukuenftigen CSM-Bootpfad mit demselben
GOP-Code. Die dabei entstehende Datei liegt nur unter build/full/ und ist
ausdruecklich NICHT der Test dieses Schritts. Sie ist nicht als fertige
XP-Bootdatei ausgeliefert. Der passende generische XP-Treiber fehlt noch.

full_build_verification.json dokumentiert die PE/UEFI-Buildpruefung.
host_tests.json dokumentiert die Tests mit simulierten Firmwareantworten.
Die aus CSM33 uebernommenen BIOS-/Timer-Bytes sind unveraendert; der Build
vergleicht sie mit der beigefuegten Originaldatei.
Das Pruefbild wurde zusaetzlich aus denselben Zeichenfunktionen auf dem Host
gerendert und visuell kontrolliert. Ein Test auf echter Hardware steht aus.

QUELLEN UND BASIS
-----------------
source/ enthaelt den vollstaendigen aktuellen Quellcode und die Buildskripte.
baseline/ enthaelt das hochgeladene CSM33-Paket als unveraenderte Basis.
changes.patch zeigt die Aenderungen an der CSM-Quelldatei und am GOP-Selector.

UEFI Graphics Output Protocol, QueryMode/SetMode und FrameBufferBase:
https://uefi.org/specs/UEFI/2.10/12_Protocols_Console_Support.html

Nach dem Hardwaretest: Den generischen XP-Grafiktreiber an die bestaetigte
GOP23V1-Uebergabe anschliessen, anschliessend dessen einfache Installation
im bereits startenden XP pruefen. Fuer iGPU und GT 730 soll dasselbe Paket
verwendet werden, jeweils auf der vom UEFI aktivierten Grafikausgabe.
